Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Emit errors/warns on some wrong uses of rustdoc attributes #80300

Merged
merged 4 commits into from
May 11, 2021
Merged

Emit errors/warns on some wrong uses of rustdoc attributes #80300

merged 4 commits into from
May 11, 2021
+367 −94

Conversation

LeSeulArtichaut
Copy link
Contributor

@LeSeulArtichaut LeSeulArtichaut commented Dec 22, 2020 •
edited by GuillaumeGomez
Loading

This PR adds a few diagnostics:

  • error if conflicting #[doc(inline)]/#[doc(no_inline)] are found
  • introduce the invalid_doc_attributes lint (warn-by-default) which triggers:
    • if a crate-level attribute is used on a non-crate item
    • if #[doc(inline)]/#[doc(no_inline)] is used on a non-use item

The code could probably be improved but I wanted to get feedback first. Also, some of those changes could be considered breaking changes, so I don't know what the procedure would be? And finally, for the warnings, they are currently hard warnings, maybe it would be better to introduce a lint? (EDIT: introduced the invalid_doc_attributes lint)

Closes #80275.
r? @jyn514

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Dec 22, 2020
@jyn514
Copy link
Member

jyn514 commented Dec 22, 2020

I think this should probably go through FCP - I'll take a look at the code first so the review isn't intermingled with the policy change.

jyn514
jyn514 reviewed Dec 22, 2020
View reviewed changes
Copy link
Member

@jyn514 jyn514 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few comments, and I think it would be helpful for @estebank to take a look if you have time.

src/librustdoc/visit_ast.rs Outdated Show resolved Hide resolved
src/librustdoc/visit_ast.rs Outdated Show resolved Hide resolved
src/librustdoc/visit_ast.rs Outdated Show resolved Hide resolved
src/test/rustdoc-ui/check-doc-attrs.rs Outdated Show resolved Hide resolved
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@LeSeulArtichaut LeSeulArtichaut force-pushed the 80275-doc-inline branch 2 times, most recently from b790ab6 to febf1d5 Compare December 22, 2020 17:33
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@GuillaumeGomez
Copy link
Member

Also, it could be interesting to add a macro like https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/macro.struct_span_err.html for warnings (but without error code).

@jyn514
Copy link
Member

jyn514 commented Dec 26, 2020

Also, it could be interesting to add a macro like https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/macro.struct_span_err.html for warnings (but without error code).

I think that's https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.struct_span_lint_hir.

@rust-log-analyzer

This comment has been minimized.

Sign in to view
jyn514
jyn514 reviewed Dec 26, 2020
View reviewed changes
src/librustdoc/visit_ast.rs Outdated Show resolved Hide resolved
src/test/rustdoc-ui/check-doc-attrs.stderr Outdated Show resolved Hide resolved
src/test/rustdoc-ui/check-doc-attrs.stderr Outdated Show resolved Hide resolved
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@LeSeulArtichaut

This comment has been minimized.

Sign in to view
@jyn514 jyn514 added A-diagnostics Area: Messages for errors, warnings, and lints T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-attributes Area: Attributes (`#[…]`, `#![…]`) labels Dec 27, 2020
@LeSeulArtichaut LeSeulArtichaut added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Dec 27, 2020
jyn514
jyn514 reviewed Dec 27, 2020
View reviewed changes
src/librustdoc/visit_ast.rs Outdated Show resolved Hide resolved
@LeSeulArtichaut LeSeulArtichaut added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 8, 2021
@jyn514
Copy link
Member

jyn514 commented May 9, 2021

I don't have time to look at this.

r? @Manishearth

@rust-highfive rust-highfive assigned Manishearth and unassigned jyn514 May 9, 2021
Manishearth
Manishearth approved these changes May 10, 2021
View reviewed changes
Copy link
Member

@Manishearth Manishearth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks great, would love to have more doc comments

compiler/rustc_passes/src/check_attr.rs Show resolved Hide resolved
@LeSeulArtichaut
Copy link
Contributor Author

LeSeulArtichaut commented May 10, 2021 •
edited
Loading

@Manishearth Added a few doc comments in a separate commit. Let me know if you'd want anything else documented.

@Manishearth
Copy link
Member

@bors r+

thanks!

@bors
Copy link
Contributor

bors commented May 10, 2021

📌 Commit 6e8d0db has been approved by Manishearth

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 10, 2021
@bors
Copy link
Contributor

bors commented May 10, 2021

⌛ Testing commit 6e8d0db with merge ac17b18a35f83579e5f75a8da8a7756f4abc9b17...

@rust-log-analyzer

This comment has been minimized.

Sign in to view
@bors
Copy link
Contributor

bors commented May 10, 2021

💔 Test failed - checks-actions

@bors bors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels May 10, 2021
@LeSeulArtichaut
Copy link
Contributor Author

LeSeulArtichaut commented May 10, 2021 •
edited
Loading

This is the only case of invalid #[doc(inline)]/#[doc(no_inline)] I found in std::{os,sys} so we should be good now

@Manishearth
Copy link
Member

@bors r+

@bors
Copy link
Contributor

bors commented May 11, 2021

📌 Commit 804ab9f has been approved by Manishearth

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 11, 2021
@bors
Copy link
Contributor

bors commented May 11, 2021

⌛ Testing commit 804ab9f with merge fe62c6e...

@bors
Copy link
Contributor

bors commented May 11, 2021

☀️ Test successful - checks-actions
Approved by: Manishearth
Pushing fe62c6e to master...

@bors bors added the merged-by-bors This PR was explicitly merged by bors. label May 11, 2021
@bors bors merged commit fe62c6e into rust-lang:master May 11, 2021
@rustbot rustbot added this to the 1.54.0 milestone May 11, 2021
@LeSeulArtichaut LeSeulArtichaut deleted the 80275-doc-inline branch May 11, 2021 11:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jyn514 jyn514 jyn514 left review comments

@pickfire pickfire pickfire left review comments

@estebank estebank estebank left review comments

@GuillaumeGomez GuillaumeGomez GuillaumeGomez approved these changes

@Manishearth Manishearth Manishearth approved these changes

Assignees

@Manishearth Manishearth

Labels
A-attributes Area: Attributes (`#[…]`, `#![…]`) A-diagnostics Area: Messages for errors, warnings, and lints disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. finished-final-comment-period The final comment period is finished for this PR / Issue. merged-by-bors This PR was explicitly merged by bors. S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.54.0
Development

Successfully merging this pull request may close these issues.

Rustdoc should give an error if you set both doc(inline) and doc(no_inline)